docs: separate FPM metadata from optional analytical integration - #229

Superseded by #248. The commits from this PR are included in d03a09f8ee6f762422aa26088621f5ff1abe6299 on feat/fpm-config-onboarding. Its refreshed model-integration guide now describes the available class-independent direct-FPM workflow and optional registered-model/SOL integration using current APIs. Continue review in #248, which remains a draft.

The original proposal and its historical evidence are retained below.

Why and what changed

FPM onboarding needs pinned model/deployment metadata, correct resource accounting, and matching whole-forward timing data. The guide separates those shared requirements from the optional procedure for reusing or implementing a registered analytical model. It documents the currently available registered-model/SOL route and the class-independent route planned in a separate decoupling PR, without making an op-level class a universal onboarding prerequisite.

The registered-model procedure covers operation construction, memory/cache accounting, the native FPM analytical contract, and installing a reviewed integration. Its runnable Qwen3-0.6B CPU example distinguishes SOL_FULL diagnostics from FPM interpolation and needs no model weights, GPU, or matching timing pair. Per-operation GPU timing collection is not required. Entry links from the model and FPM workflow guides identify the route choice explicitly.

The planned class-independent route uses validated metadata and direct measured-time interpolation with wider two-sided KV brackets; 2D interpolation remains experimental. Inkling on GB200 with TP, DEP, and TEP is the planned pilot. This documentation introduces no class-independent API or Inkling implementation, and it states that the separate guided foundation currently generates pure-TP configurations only.

Review map

• Risk: low; documentation only.
• Start with python/aisimulate/docs/fpm/model-integration.md, especially the current/planned route distinction and the conditional registered-model transfer-path tests.
• Public or serialized contract changed: no. Every existing code block is unchanged.
• The PR is based on main and can merge independently of the CLI foundation and decoupling implementation.

Evidence

Updated head: d338ebc37f2c6e4abc496975bce9e05c33e8a55a.

• Reran the documented CPU example with source-scoped imports and the existing native wheel: retained graphs, expected geometry and per-rank weight/KV accounting, native memory sizing, and finite analytical diagnostics pass.
• Documentation checks pass for 64 Markdown files; seven link tests and whitespace checks pass. All documented code blocks match the prior guide.
• Historical baseline caca6d0f304dc660cce5a12c88cd58ecf6c09270: Python FPM/OpSpec/single-oracle contracts passed 37 tests; native FPM SOL passed 16 and native FPM forward passed 17. Independent reviews, Fast CI, and Full CI passed on that baseline. Those results are historical, not hosted evidence for the documentation update.
• Hosted checks and applicable human CODEOWNER approval must cover the updated head. The PR remains draft.

Modeling and data provenance

No performance data or model implementation is added. Examples use bundled Qwen metadata, the H200 catalog, and CPU analytical checks. The values are analytical estimates rather than measured latency or peak serving memory. Existing contract tests use synthetic fixtures. No GPU collection, Inkling readiness, or predictive accuracy is claimed.

Tracking

Refs AIC-1963 onboarding guidance and AIC-1964 model/resource metadata. Related foundation: #196. The separate decoupling PR implements AIC-1964, AIC-1990, and AIC-1991; this guide does not complete those implementation issues.

The decoupling PR will validate actual CLI predict, recommend, and exported replay against existing MiniMax-M2.7 H200 TP4 and GLM-5.2-NVFP4 B200 DEP8/TEP8 FPM data, including explicit GLM FP8 FMHA identity and classless resource metadata.